{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-spectrum/meter';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/meter/package.json';

```jsx import
import {Flex} from '@react-spectrum/layout';
import {Meter} from '@react-spectrum/meter';
```

---
category: Status
---

# Meter

<PageDescription>{docs.exports.Meter.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['Meter']}
  sourceData={[{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/meter/'}]}
  since="3.0.0" />

## Example

```tsx example
<Meter label="Storage space" value={35} />
```

## Value

Meters are controlled with the `value` prop.
By default, the `value` prop represents the current percentage of progress, as the minimum and maximum values default to 0 and 100, respectively.

```tsx example
<Meter
  label="Storage space"
  value={25} />
```

Alternatively, a different scale can be used by setting the `minValue` and `maxValue` props.

```tsx example
<Meter
  label="Widgets Used"
  minValue={50}
  maxValue={150}
  value={100} />
```

Values are formatted as a percentage by default, but this can be modified by using the `formatOptions` prop to specify a different format.
`formatOptions` is compatible with the option parameter of [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) and is applied based on the current locale.

```tsx example
<Meter
  label="Currency"
  formatOptions={{style: 'currency', currency: 'JPY'}}
  value={60} />
```

## Labeling
Value labels are shown above the Meter by default, but they can also be moved to the side or hidden as needed.
The label text should be in sentence case.

```tsx example
<Flex direction="column" maxWidth="size-3000" gap="size-300">
  <Meter label="Label" value={25} variant="warning" />
  <Meter label="Label" labelPosition="side" value={25} variant="warning" />
  <Meter label="Label" showValueLabel={false} value={25} variant="warning" />
</Flex>
```

The value label can be updated via the `valueLabel` prop in cases where showing a different scale makes sense.
```tsx example
<Meter label="Progress" marginBottom="size-300" value={25} valueLabel="1 of 4" variant="warning" />
```

By default, the value label is formatted as a percentage. This can be customized using the following props.

* `showValueLabel`: Allows you to display or hide the value label.
* `formatOptions`: Allows you to customize the format of the value.
* `valueLabel`: Allows you to customize the value label to any string.

```tsx example
<Flex direction="column" maxWidth="size-3000" gap="size-300">
  <Meter
    label="Space used"
    showValueLabel={false}
    value={90}
    variant="critical" />

  <Meter
    label="Space used"
    valueLabel="54 of 60GB"
    value={90} variant="critical" />

  <Meter
    label="Space used"
    formatOptions={{style: 'percent', minimumFractionDigits: 2}}
    value={89.123}
    variant="critical" />
</Flex>
```

### Accessibility

Depending on the visualization being used (i.e. depending on the `showValueLabel` prop), a `label`, `aria-label`, or `aria-labelledby` prop is required.

### Internationalization

To internationalize a Meter, a localized string should be passed to the `label` prop, `aria-label` prop, or value of the associated `aria-labelledby` element.

For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the meter is automatically flipped. In addition,
Meter automatically uses the current locale to format the value label.

## Props

<PropTable component={docs.exports.Meter} links={docs.links} />

## Visual options

### Size
[View guidelines](https://spectrum.adobe.com/page/meter/#Size)

```tsx example
<Flex direction="column" gap="size-300">
  <Meter label="Space used" size="S" value={90} variant="critical" />
  <Meter label="Space used" size="L" value={90} variant="critical" />
</Flex>
```

### Variants
[View guidelines](https://spectrum.adobe.com/page/meter/#Options)

```tsx example
<Flex direction="column" gap="size-300">
  <Meter label="Space used" value={25} variant="informative" />
  <Meter label="Space used" value={25} variant="positive" />
  <Meter label="Space used" value={90} variant="critical" />
  <Meter label="Space used" value={70} variant="warning" />
</Flex>
```
